/*
 * Copyright (C) 2010-2011 Comcast Cable.  All Rights Reserved.
 */
package com.hercules.android.receiver.connection;

import com.hercules.android.receiver.AndroidReceiver;
import com.hercules.android.receiver.model.events.XREConnectEvent;
import com.hercules.android.receiver.model.events.XREEvent;

/**
 * <p>
 * This interface provides the methods needed to abstract the communication protocol between receivers and server.
 * </p>
 * <p>
 * It provides methods to connect to a server, send messages to a server and disconnect from a server.
 * </p>
 * <p>
 * <strong> Thread safety:</strong> Implementations are required to be thread safe with reasonable assumptions that each
 * implementation should provide.
 * </p>
 *
 * @author DanLazar, morehappiness
 * @version 1.0
 */
public interface ServerConnection {
    /**
     * This method connects the given receiver to a server. Should be called only once by each receiver, at startup.
     * <p>
     * AndroidAssembly3 event parameter is changed to {@link XREConnectEvent}
     *
     * @param onConnectEvent the connection event
     * @param receiver the receiver for which connection is created
     * @throws IllegalArgumentException if either parameter is null
     * @throws ServerConnectionException if any error occurs while connecting to the server
     */
    void connect(XREConnectEvent onConnectEvent, AndroidReceiver receiver) throws ServerConnectionException;

    /**
     * This method will send the event to a server using the receiver connection identified by the given sessionGUID.
     * <p>
     * AndroidAssembly3 sending to receiver
     *
     * @param receiver the receiver to use
     * @param event the event that will be sent to the server
     * @throws IllegalArgumentException if any parameter is null or sessionGUID is empty string
     * @throws ServerConnectionException if any errors occurred while sending the event
     */
    void send(XREEvent event, AndroidReceiver receiver) throws ServerConnectionException;

    /**
     * Closes the connection for the receiver identified by the given sessionGUID.
     *
     * @param sessionGUID the session identifier
     * @throws IllegalArgumentException if sessionGUID is null/empty string
     * @throws ServerConnectionException if any error occurs while closing the connection
     */
    void close(String sessionGUID) throws ServerConnectionException;
}
